﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>文件对象 - 方法 &amp; 属性 | AutoHotkey v2</title>
<meta name="description" content="The file object provides an interface for a file to perform actions, such as reading or writing data, or to retrieve or set values, such as length." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>文件对象</h1>

<p>提供文件输入/输出的接口. <a href="../commands/FileOpen.htm">FileOpen</a> 返回此类型的对象.</p>

<h2 id="Members">对象成员</h2>
<p>属性:</p>
<ul>
  <li><a href="#Pos">Pos</a>: 检索或设置文件指针的位置.</li>
  <li><a href="#Length">Length</a>: 检索或设置文件的大小.</li>
  <li><a href="#AtEOF">AtEOF</a>: 检索一个非零值, 如果文件指针已到达文件末尾.</li>
  <li><a href="#Encoding">Encoding</a>: 检索或设置此文件对象使用的文本编码.</li>
  <li><a href="#Handle">Handle</a>: 检索旨在与 DllCall 一起使用的系统文件句柄.</li>
</ul>
<p>方法:</p>
<ul>
  <li><a href="#Read">Read</a>: 从文件中读取字符串, 并向前移动文件指针(向右).</li>
  <li><a href="#Write">Write</a>: 写入字符串到文件并向前移动文件指针.</li>
  <li><a href="#ReadLine">ReadLine</a>: 从文件中读取一行文本并向前移动文件指针.</li>
  <li><a href="#WriteLine">WriteLine</a>: 根据打开文件时使用的标志, 写入后面跟着 <code>`n</code> 或 <code>`r`n</code> 的字符串. 向前移动文件指针.</li>
  <li><a href="#ReadNum">Read<em>NumType</em></a>: Reads a number from the file and advances the file pointer.</li>
  <li><a href="#WriteNum">Write<em>NumType</em></a>: Writes a number to the file and advances the file pointer.</li>
  <li><a href="#RawRead">RawRead</a>: Reads raw binary data from the file into memory and advances the file pointer.</li>
  <li><a href="#RawWrite">RawWrite</a>: Writes raw binary data to the file and advances the file pointer.</li>
  <li><a href="#Seek">Seek</a>: Moves the file pointer. If the second parameter is omitted, it is equivalent to <code>File.Pos := Distance</code>.</li>
  <li><a href="#Close">Close</a>: Closes the file, flushes any data in the cache to disk and releases the share locks.</li>
</ul>

<div class="methodShort" id="Read"><h2>Read</h2>
<p>Reads a string of characters from the file and advances the file pointer.</p>
<pre class="Syntax">String := File.<span class="func">Read</span>(<span class="optional">Characters</span>)</pre>
<dl>
  <dt>Characters</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>The maximum number of characters to read. If omitted, the rest of the file is read and returned as one string. If the File object was created from a handle to a non-seeking device such as a console buffer or pipe, omitting this parameter may cause the method to fail or return only what data is currently available.</p>
  </dd>
</dl>
<p><strong>Returns</strong> a string.</p>
</div>

<div class="methodShort" id="Write"><h2>Write</h2>
<p>Writes a string of characters to the file and advances the file pointer.</p>
<pre class="Syntax">File.<span class="func">Write</span>(String)</pre>
<dl>
  <dt>String</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>A string to write.</p>
  </dd>
</dl>
<p><strong>Returns</strong> the number of bytes (not characters) that were written.</p>
</div>

<div class="methodShort" id="ReadLine"><h2>ReadLine</h2>
<p>Reads a line of text from the file and advances the file pointer.</p>
<pre class="Syntax">TextLine := File.<span class="func">ReadLine</span>()</pre>
<p><strong>Returns</strong> a line of text, excluding the line ending.</p>
<p>Lines up to 65,534 characters long can be read. If the length of a line exceeds this, the remainder of the line is returned by subsequent calls to this method.</p></div>

<div class="methodShort" id="WriteLine"><h2>WriteLine</h2>
<p>Writes a string of characters followed by <code>`n</code> or <code>`r`n</code> depending on the flags used to open the file. Advances the file pointer.</p>
<pre class="Syntax">File.<span class="func">WriteLine</span>(<span class="optional">String</span>)</pre>
<dl>
  <dt>String</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>An optional string to write.</p>
  </dd>
</dl>
<p><strong>Returns</strong> the number of bytes (not characters) that were written.</p>
</div>

<div class="methodShort" id="ReadNum"><h2>Read<i>NumType</i></h2>
<p>Reads a number from the file and advances the file pointer.</p>
<pre class="Syntax">Num := File.Read<i>NumType</i>()</pre>
<p><em>NumType</em> is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with <a href="../commands/DllCall.htm#types">DllCall</a>.</p>
<p><strong>Returns</strong> a number if the read was successful, otherwise an empty string. If the number of bytes read is non-zero but less than the size of <em>NumType</em>, the missing bytes are assumed to be zero.</p>
</div>

<div class="methodShort" id="WriteNum"><h2>Write<i>NumType</i></h2>
<p>Writes a number to the file and advances the file pointer.</p>
<pre class="Syntax">File.Write<i>NumType</i>(Num)</pre>
<dl>
  <dt>Num</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a> or <a href="../Concepts.htm#numbers">Float</a></p>
    <p>A number to write.</p>
  </dd>
</dl>
<p><em>NumType</em> is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with <a href="../commands/DllCall.htm#types">DllCall</a>.</p>
<p><strong>Returns</strong> the number of bytes that were written. For instance, WriteUInt returns 4 if successful.</p>
</div>

<div class="methodShort" id="RawRead"><h2>RawRead</h2>
<p>Reads raw binary data from the file into memory and advances the file pointer.</p>
<pre class="Syntax">File.<span class="func">RawRead</span>(Buffer <span class="optional">, Bytes</span>)</pre>
<dl>
  <dt>Buffer</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#objects">对象</a>, <a href="../Concepts.htm#variables">变量</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>The <a href="Buffer.htm">Buffer</a>-like object, variable or memory address which will receive the data.</p>
    <p>Reading into a <a href="Buffer.htm">Buffer</a> created by <a href="../commands/BufferAlloc.htm">BufferAlloc</a> is recommended. If <em>Bytes</em> is omitted, it defaults to the size of the buffer. An exception is thrown if <em>Bytes</em> exceeds the size of the buffer.</p>
    <p>To read to a memory address, pass a pure integer such as <code>&amp;variable + offset</code> or a variable containing a pure integer. In this case, <em>Bytes</em> must also be specified.</p>
    <p class="warning"><strong>Deprecated:</strong> To read into a variable, pass a variable which is empty or contains a string. If <em>Bytes</em> is omitted, it defaults to the capacity of the variable. If <em>Bytes</em> is greater than the capacity of the variable, the variable is expanded. After the data is read, the variable's length is set to the string length of the data (rounded up to a whole number).</p>
  </dd>
  <dt>Bytes</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>The maximum number of bytes to read. This is optional when <em>Buffer</em> is an object or (deprecated) string variable; otherwise, it is required.</p>
  </dd>
</dl>
<p><strong>Returns</strong> the number of bytes that were read.</p>
</div>

<div class="methodShort" id="RawWrite"><h2>RawWrite</h2>
<p>Writes raw binary data to the file and advances the file pointer.</p>
<pre class="Syntax">File.<span class="func">RawWrite</span>(Data <span class="optional">, Bytes</span>)</pre>
<dl>
  <dt>Data</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#objects">对象</a>, <a href="../Concepts.htm#strings">字符串</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>A <a href="Buffer.htm">Buffer</a>-like object or string containing binary data, or a memory address. If an object or string is specified, <em>Bytes</em> is optional and defaults to the size of the buffer or string. Otherwise, <em>Bytes</em> must also be specified.</p>
    <p>To write data from a given memory address, pass a pure integer such as <code>&amp;variable + offset</code> or a variable containing a pure integer.</p>
  </dd>
  <dt>Bytes</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>The number of bytes to write. This is optional when <em>Data</em> is an object or string; otherwise, it is required.</p>
  </dd>
</dl>
<p><strong>Returns</strong> the number of bytes that were written.</p>
</div>

<div class="methodShort" id="Seek"><h2>Seek</h2>
<p>Moves the file pointer.</p>
<pre class="Syntax">File.<span class="func">Seek</span>(Distance <span class="optional">, Origin := 0</span>)
</pre>
<dl>
  <dt>Distance</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>Distance to move, in bytes. Lower values are closer to the beginning of the file.</p>
  </dd>
  <dt>Origin</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>Starting point for the file pointer move. Must be one of the following:</p>
    <ul>
      <li>0 (SEEK_SET): Beginning of the file. <i>Distance</i> must be zero or greater.</li>
      <li>1 (SEEK_CUR): Current position of the file pointer.</li>
      <li>2 (SEEK_END): End of the file. <i>Distance</i> should usually be negative.</li>
    </ul>
    <p>If omitted, <i>Origin</i> defaults to SEEK_END when Distance is negative and SEEK_SET otherwise.</p></dd>
</dl>
<p><strong>Returns</strong> a non-zero value if successful, otherwise zero.</p>
</div>

<div class="methodShort" id="Pos"><h2>Pos</h2>
<p>Retrieves or sets the current position of the file pointer.</p>
<pre class="Syntax">Pos := File.Pos</pre>
<pre class="Syntax">File.Pos := NewPos</pre>
<p>Equivalent to <code>File.Seek(NewPos)</code>.</p>
<p>The position is a byte offset from the beginning of the file, where 0 is the first byte. When data is written to or read from the file, the file pointer automatically moves to the next byte after that data.</p>
</div>

<div class="methodShort" id="Length"><h2>Length</h2>
<p>Retrieves or sets the size of the file.</p>
<pre class="Syntax">FileSize := File.Length</pre>
<pre class="Syntax">File.Length := NewSize</pre>
<p><em>FileSize</em> and <em>NewSize</em> is the size of the file, in bytes.</p>
<p>This property should be used only with an actual file. If the File object was created from a handle to a pipe, it may return the amount of data currently available in the pipe's internal buffer, but this behaviour is not guaranteed.</p></div>

<div class="methodShort" id="AtEOF"><h2>AtEOF</h2>
  <p>Retrieves a non-zero value if the file pointer has reached the end of the file, otherwise zero.</p>
<pre class="Syntax">IsAtEOF := File.AtEOF</pre>
  <p>This property should be used only with an actual file. If the File object was created from a handle to a non-seeking device such as a console buffer or pipe, the returned value may not be meaningful, as such devices do not logically have an "end of file".</p></div>

<div class="methodShort" id="Close"><h2>Close</h2>
<p>Closes the file, flushes any data in the cache to disk and releases the share locks.</p>
<pre class="Syntax">File.<span class="func">Close</span>()</pre>
<p>&nbsp;Although the file is closed automatically when the object is freed, it is recommended to close the file as soon as possible.</p></div>

<div class="methodShort" id="Encoding"><h2>Encoding</h2>
<p>Retrieves or sets the text encoding used by this file object.</p>
<pre class="Syntax">RetrievedEncoding := File.Encoding</pre>
<pre class="Syntax">File.Encoding := NewEncoding</pre>
  <p><em>RetrievedEncoding</em> and <em>NewEncoding</em> is a numeric code page identifier (see <a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">MSDN</a>) or one of the following strings:</p>
  <ul>
	<li><code>UTF-8</code>: Unicode UTF-8, equivalent to CP65001.</li>
	<li><code>UTF-16</code>: Unicode UTF-16 with little endian byte order, equivalent to CP1200.</li>
	<li><code>CP<i>nnn</i></code>: a code page with numeric identifier <i>nnn</i>.</li>
  </ul>
  <p><em>RetrievedEncoding</em> is never a value with the <code>-RAW</code> suffix, regardless of how the file was opened or whether it contains a byte order mark (BOM). Setting <em>NewEncoding</em> never causes a BOM to be added or removed, as the BOM is normally written to the file when it is first created.</p>
  <p>Setting <em>NewEncoding</em> to <code>UTF-8-RAW</code> or <code>UTF-16-RAW</code> is valid, but the <code>-RAW</code> suffix is ignored. This only applies to <code>File.Encoding</code>, not <a href="../commands/FileOpen.htm">FileOpen</a>.</p>
</div>

<div class="methodShort" id="Handle"><h2>Handle</h2>
  <p>Returns a system file handle, intended for use with DllCall. See <a href="http://msdn.microsoft.com/en-us/library/aa363858.aspx">CreateFile</a>.</p>
<pre class="Syntax">File.Handle</pre>
<p>File objects internally buffer reads or writes. If data has been written into the object's internal buffer, it is committed to disk before the handle is returned. If the buffer contains data read from file, it is discarded and the actual file pointer is reset to the logical position indicated by <code>File.Pos</code>.</p></div>

</body>
</html>